Document state management architecture principles

Add critical guidelines for deriving player state from MPV rather
than maintaining duplicate state. Documents the single source of
truth pattern to prevent state synchronization bugs.

CLAUDE.md

@@ -14,6 +14,29 @@ A high-performance Rust-based TUI player for playing music and video files. Buil
 
 ## Architecture
 
+### State Management
+
+**CRITICAL:** Player state must be derived from MPV, not maintained separately.
+
+**Single Source of Truth:** MPV properties via IPC
+- `idle-active` (bool) - No file loaded or file ended
+- `pause` (bool) - Playback is paused
+
+**Derive PlayerState:**
+```rust
+if player.is_idle → PlayerState::Stopped
+if !player.is_idle && player.is_paused → PlayerState::Paused
+if !player.is_idle && !player.is_paused → PlayerState::Playing
+```
+
+**Rationale:**
+- Eliminates state synchronization bugs
+- MPV is always the authoritative source
+- No need to update state in multiple places
+- Simpler auto-play logic
+
+**Anti-pattern:** DO NOT maintain `state.player_state` that can desync from MPV
+
 ### Cache-Only Operation
 
 **CRITICAL:** Left panel shows ONLY cached data. Never browse filesystem directly during operation.