feat: enhance audio analysis session API documentation with upload requirements and processing steps

Author: Thavarshan

README.md

@@ -88,17 +88,28 @@ Requires `Authorization: Bearer <token>`. Uses Cerberus token introspection, ret
 
 ### POST `/api/sessions`
 
+Creates a new audio analysis session. Requires authentication.
+
+**Important**: The `uploadUrl` must point to a publicly accessible audio file hosted on cloud storage (S3, CDN, etc.). The API does not handle file uploads directly - users must upload their files separately and provide the URL.
+
 Body:
 
 ```jsonc
 {
   "sessionId": "mix-42",
-  "uploadUrl": "https://cdn.example.com/mix.wav",
-  "userContext": { "daw": "Ableton Live" },
+  "uploadUrl": "https://cdn.example.com/mix.wav",  // Must be publicly accessible HTTPS URL
+  "userContext": { "daw": "Ableton Live", "genre": "House", "experienceLevel": "intermediate" }
 }
 ```
 
-Response: `EngineState` from `@auralyze/engine`. Include `Authorization: Bearer <token>` obtained from Cerberus (or the local JWT fallback).
+The API will:
+
+1. Extract metadata (duration, format, sample rate) via metadata service
+2. Perform audio analysis (loudness, dynamics, spectrum, stereo) via analysis service
+3. Generate AI feedback via feedback service (OpenAI GPT-4)
+4. Store complete results in database
+
+Response: `EngineState` from `@auralyze/engine` with all analysis results. Include `Authorization: Bearer <token>` or authenticate via httpOnly cookie.
 
 ## Security & Release