fixing leveling xp reporting

api/docs/GAME_SYSTEMS.md

@@ -401,6 +401,12 @@ XP Required = 100 × (current_level ^ 1.5)
 - Level up triggers automatically when threshold reached
 - Base stats remain constant (progression via skill trees & equipment)
 
+**XP Tracking:**
+- **`experience`**: Current progress toward next level (0 to required XP, resets on level-up)
+- **`total_xp`**: Cumulative XP earned across all levels (never decreases)
+- **UI Display**: Shows both values (e.g., "Total XP: 150 | Progress: 50/282 to Level 3")
+- **Legacy data**: Characters without `total_xp` default to 0, will track from next XP gain
+
 **Implementation:**
 - Leveling logic lives in `Character` model (`add_experience()`, `level_up()` methods)
 - No separate service needed (OOP design pattern)