Implement Phase 3 Music Analysis and LLM Engine

- Refactor Database: Add `Artist` model, M2M relationship, and `AnalysisSnapshot` model.
- Backend Services: Implement `StatsService` for computable metrics and `NarrativeService` for Gemini LLM integration.
- Fix Ingestion: Correctly handle multiple artists per track and backfill existing data.
- Testing: Add unit tests for statistics logic and live verification scripts.
- Documentation: Add `PHASE_4_FRONTEND_GUIDE.md`.

PHASE_4_FRONTEND_GUIDE.md

@@ -0,0 +1,84 @@
+# Phase 4 Frontend Implementation Guide
+
+This guide details how to consume the data generated by the Phase 3 Backend (Analysis & LLM Engine) and how to display it in the frontend.
+
+## 1. Data Source
+
+The backend now produces **Analysis Snapshots**. You should create an API endpoint (e.g., `GET /api/analysis/latest`) that returns the most recent snapshot.
+
+### JSON Payload Structure
+
+The response object contains two main keys: `metrics_payload` (calculated numbers) and `narrative_report` (LLM text).
+
+```json
+{
+  "id": 1,
+  "date": "2024-12-25T12:00:00Z",
+  "period_label": "last_30_days",
+  "metrics_payload": {
+    "volume": { ... },
+    "time_habits": { ... },
+    "sessions": { ... },
+    "vibe": { ... },
+    "era": { ... },
+    "skips": { ... }
+  },
+  "narrative_report": {
+    "vibe_check": "...",
+    "patterns": ["..."],
+    "persona": "...",
+    "roast": "..."
+  }
+}
+```
+
+---
+
+## 2. UI Components & Display Strategy
+
+### A. Hero Section ("The Vibe Check")
+**Data Source:** `narrative_report`
+- **Headline:** Display `narrative_report.persona` as a large badge/title (e.g., "The Focused Fanatic").
+- **Narrative:** Display `narrative_report.vibe_check` as the main text.
+- **Roast:** Add a small, dismissible "Roast Me" alert box containing `narrative_report.roast`.
+
+### B. "The Vibe" Radar Chart
+**Data Source:** `metrics_payload.vibe`
+- Use a **Radar Chart** (Spider Chart) with the following axes (0.0 - 1.0):
+  - Energy (`avg_energy`)
+  - Valence (`avg_valence`)
+  - Danceability (`avg_danceability`)
+  - Acousticness (`avg_acousticness`)
+  - Instrumentalness (`avg_instrumentalness`)
+- **Tooltip:** Show the exact value.
+
+### C. Listening Habits (Time & Sessions)
+**Data Source:** `metrics_payload.time_habits` & `metrics_payload.sessions`
+- **Hourly Heatmap:** Use a bar chart for `metrics_payload.time_habits.hourly_distribution` (0-23 hours). Highlight the `peak_hour`.
+- **Session Stats:** Display "Average Session" stats:
+  - `sessions.avg_minutes` (mins)
+  - `sessions.avg_tracks` (tracks)
+  - `sessions.count` (total sessions)
+
+### D. Top Favorites
+**Data Source:** `metrics_payload.volume`
+- **Lists:** Display Top 5 Tracks, Artists, and Genres.
+- **Images:** You will need to fetch Artist/Track images from Spotify API using the IDs provided in the lists (the current snapshot only stores names/counts for simplicity, but the IDs are available in the backend if you expand the serializer). *Note: Phase 3 backend currently returns names. For Phase 4, ensure the API endpoint enriches these with Spotify Image URLs.*
+
+### E. Era Analysis
+**Data Source:** `metrics_payload.era`
+- **Musical Age:** Display `musical_age` (e.g., "1998") prominently.
+- **Distribution:** Pie chart for `decade_distribution`.
+
+### F. Attention Span (Skips)
+**Data Source:** `metrics_payload.skips`
+- **Metric:** Display "Skip Rate" (`skip_rate`) as a percentage.
+- **Insight:** "You skipped X tracks this month."
+
+---
+
+## 3. Integration Tips
+
+- **Caching:** The backend stores snapshots. You do NOT need to trigger a calculation on page load. Just fetch the latest snapshot.
+- **Theme:** The app uses Ant Design Dark Mode. Stick to Spotify colors (Black/Green/White) but add accent colors based on the "Vibe" (e.g., High Energy = Red/Orange, Low Energy = Blue/Purple).
+- **Expansion:** Future snapshots allow for "Trend" views. You can graph `metrics_payload.volume.total_plays` over the last 6 snapshots to show activity trends.