Update readmes and imporve UI

services/demo_session/README.md

@@ -172,30 +172,98 @@ graph TD
 - **Use Case**: Central obrador + 3 retail outlets
 - **Features**: VRP-optimized routes, multi-location inventory
 
+## 🎯 API Endpoints
+
+### Atomic Operations
+- `GET /api/v1/demo/accounts` - List available demo account types
+- `POST /api/v1/demo/sessions` - Create new demo session
+- `GET /api/v1/demo/sessions/{session_id}` - Get session details
+- `GET /api/v1/demo/sessions/{session_id}/status` - Poll cloning status
+- `GET /api/v1/demo/sessions/{session_id}/errors` - Get detailed errors
+- `DELETE /api/v1/demo/sessions/{session_id}` - Destroy session
+
+### Business Operations
+- `POST /api/v1/demo/sessions/{session_id}/extend` - Extend session TTL
+- `POST /api/v1/demo/sessions/{session_id}/retry` - Retry failed cloning
+- `GET /api/v1/demo/stats` - Session statistics
+- `POST /api/v1/demo/operations/cleanup` - Cleanup expired sessions
+- `POST /api/v1/demo/sessions/{session_id}/seed-alerts` - Seed demo alerts
+
+### Session Lifecycle
+
+**Statuses:**
+- `PENDING` - Data cloning in progress
+- `READY` - All data loaded, ready to use
+- `PARTIAL` - Some services failed, others succeeded
+- `FAILED` - One or more services failed completely
+- `EXPIRED` - Session TTL exceeded
+- `DESTROYED` - Session terminated
+
+**Session Duration:**
+- Default: 2 hours
+- Extendable via `/extend` endpoint
+- Extension limit: Configurable per environment
+
+**Estimated Load Times:**
+- Professional: ~40 seconds
+- Enterprise: ~75 seconds (includes child tenants)
+
 ## 🔧 Usage
 
 ### Create Demo Session via API
 
 ```bash
 # Professional demo
-curl -X POST http://localhost:8000/api/v1/demo-sessions \
+curl -X POST http://localhost:8000/api/v1/demo/sessions \
   -H "Content-Type: application/json" \
   -d '{
     "demo_account_type": "professional",
-    "email": "test@example.com",
-    "subscription_tier": "professional"
+    "email": "test@example.com"
   }'
 
-# Enterprise demo  
-curl -X POST http://localhost:8000/api/v1/demo-sessions \
+# Enterprise demo
+curl -X POST http://localhost:8000/api/v1/demo/sessions \
   -H "Content-Type: application/json" \
   -d '{
     "demo_account_type": "enterprise",
-    "email": "test@example.com",
-    "subscription_tier": "enterprise"
+    "email": "test@example.com"
   }'
 ```
 
+### Poll Session Status
+
+```bash
+# Check if session is ready
+curl http://localhost:8000/api/v1/demo/sessions/{session_id}/status
+
+# Response includes per-service progress
+{
+  "session_id": "demo_xxx",
+  "status": "ready|pending|failed|partial",
+  "progress": {
+    "orders": {"status": "completed", "records": 42},
+    "production": {"status": "in_progress", "records": 15}
+  },
+  "estimated_remaining_seconds": 30
+}
+```
+
+### Session Management
+
+```bash
+# Extend session (add more time)
+curl -X POST http://localhost:8000/api/v1/demo/sessions/{session_id}/extend
+
+# Retry failed services
+curl -X POST http://localhost:8000/api/v1/demo/sessions/{session_id}/retry
+
+# Get session details
+curl http://localhost:8000/api/v1/demo/sessions/{session_id}
+
+# Destroy session (cleanup)
+curl -X DELETE http://localhost:8000/api/v1/demo/sessions/{session_id}
+```
+
 ### Implementation Example
 
 Here's how the Orders service implements direct loading:
@@ -392,11 +460,12 @@ def adjust_date_for_demo(original_date: datetime, session_time: datetime) -> dat
 
 ### Step-by-Step Demo Session Creation
 
-1. **User Request**: Frontend calls `/api/v1/demo-sessions` with demo type
+1. **User Request**: Frontend calls `/api/v1/demo/sessions` with demo type
 2. **Session Setup**: Demo Session Service:
    - Generates virtual tenant UUID
-   - Records session metadata
-   - Calculates session creation timestamp
+   - Records session metadata (session_id, ip_address, user_agent)
+   - Calculates session creation timestamp and expiration
+   - For enterprise: Generates child tenant IDs
 3. **Parallel Service Calls**: Demo Session Service calls each service's `/internal/demo/clone` endpoint with:
    - `virtual_tenant_id` - Virtual tenant UUID
    - `demo_account_type` - Profile (professional/enterprise)
@@ -406,8 +475,10 @@ def adjust_date_for_demo(original_date: datetime, session_time: datetime) -> dat
    - Transforms all IDs using XOR with virtual tenant ID
    - Adjusts all dates relative to session creation time
    - Inserts data into its database within a transaction
-   - Returns success/failure status
-5. **Response**: Demo Session Service returns credentials and session info
+   - Returns success/failure status with record count
+5. **Status Tracking**: Per-service progress stored in JSONB field with timestamps and error details
+6. **Response**: Demo Session Service returns credentials and session info
+7. **Frontend Polling**: Frontend polls `/api/v1/demo/sessions/{session_id}/status` until status is READY or FAILED
 
 ### Example: Orders Service Clone Endpoint