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`.

backend/alembic/versions/4401cb416661_add_artist_and_snapshot_models.py

@@ -0,0 +1,63 @@
+"""Add Artist and Snapshot models
+
+Revision ID: 4401cb416661
+Revises: 707387fe1be2
+Create Date: 2025-12-24 23:06:59.235445
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '4401cb416661'
+down_revision: Union[str, Sequence[str], None] = '707387fe1be2'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('analysis_snapshots',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('date', sa.DateTime(), nullable=True),
+    sa.Column('period_start', sa.DateTime(), nullable=True),
+    sa.Column('period_end', sa.DateTime(), nullable=True),
+    sa.Column('period_label', sa.String(), nullable=True),
+    sa.Column('metrics_payload', sa.JSON(), nullable=True),
+    sa.Column('narrative_report', sa.JSON(), nullable=True),
+    sa.Column('model_used', sa.String(), nullable=True),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_index(op.f('ix_analysis_snapshots_date'), 'analysis_snapshots', ['date'], unique=False)
+    op.create_index(op.f('ix_analysis_snapshots_id'), 'analysis_snapshots', ['id'], unique=False)
+    op.create_table('artists',
+    sa.Column('id', sa.String(), nullable=False),
+    sa.Column('name', sa.String(), nullable=True),
+    sa.Column('genres', sa.JSON(), nullable=True),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_index(op.f('ix_artists_id'), 'artists', ['id'], unique=False)
+    op.create_table('track_artists',
+    sa.Column('track_id', sa.String(), nullable=False),
+    sa.Column('artist_id', sa.String(), nullable=False),
+    sa.ForeignKeyConstraint(['artist_id'], ['artists.id'], ),
+    sa.ForeignKeyConstraint(['track_id'], ['tracks.id'], ),
+    sa.PrimaryKeyConstraint('track_id', 'artist_id')
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_table('track_artists')
+    op.drop_index(op.f('ix_artists_id'), table_name='artists')
+    op.drop_table('artists')
+    op.drop_index(op.f('ix_analysis_snapshots_id'), table_name='analysis_snapshots')
+    op.drop_index(op.f('ix_analysis_snapshots_date'), table_name='analysis_snapshots')
+    op.drop_table('analysis_snapshots')
+    # ### end Alembic commands ###