diff --git a/android/src/main/java/group07/beatbattle/android/AndroidAudioPlayer.java b/android/src/main/java/group07/beatbattle/android/AndroidAudioPlayer.java
index b733d12..fb48cd7 100644
--- a/android/src/main/java/group07/beatbattle/android/AndroidAudioPlayer.java
+++ b/android/src/main/java/group07/beatbattle/android/AndroidAudioPlayer.java
@@ -8,6 +8,12 @@
 
 import group07.beatbattle.audio.AudioPlayer;
 
+/**
+ * Android AudioPlayer implementation — streams audio from a URL using MediaPlayer.
+ * Audio is tagged as USAGE_GAME so the system routes it through the game audio stream.
+ * Playback starts asynchronously via prepareAsync(); mute state is preserved across
+ * player lifecycle changes (i.e. calling setMuted before play still takes effect).
+ */
 public class AndroidAudioPlayer implements AudioPlayer {
 
     private final Context context;
@@ -18,6 +24,11 @@ public AndroidAudioPlayer(Context context) {
         this.context = context;
     }
 
+    /**
+     * Stops any current track and starts streaming from the given URL.
+     *
+     * @param url the HTTP(S) URL of the audio preview to stream
+     */
     @Override
     public void play(String url) {
         stop();
@@ -41,7 +52,9 @@ public void play(String url) {
             Gdx.app.error("AndroidAudioPlayer", "Failed to play: " + url, e);
         }
     }
-
+    /**
+     * Stops any current track
+     */
     @Override
     public void stop() {
         if (mediaPlayer != null) {
@@ -50,7 +63,11 @@ public void stop() {
             mediaPlayer = null;
         }
     }
-
+    /**
+     * Mutes or unmutes the current track. Uses mediaplayer volume control.
+     *
+     * @param muted true to mute, false to unmute
+     */
     @Override
     public void setMuted(boolean muted) {
         this.muted = muted;
diff --git a/android/src/main/java/group07/beatbattle/android/DeezerMusicService.java b/android/src/main/java/group07/beatbattle/android/DeezerMusicService.java
index 1cd07d9..41497fb 100644
--- a/android/src/main/java/group07/beatbattle/android/DeezerMusicService.java
+++ b/android/src/main/java/group07/beatbattle/android/DeezerMusicService.java
@@ -17,10 +17,25 @@
 import java.util.Collections;
 import java.util.List;
 
+/**
+ * Fetches song tracks from the Deezer public API for use as quiz questions.
+ * Hits the global chart endpoint to retrieve up to 50 trending tracks, shuffles them,
+ * and returns the requested number. Only songs with a preview URL are included.
+ *
+ * Note: the chart endpoint always returns the same pool of top-50 songs,
+ * so variety is limited to shuffle order. Consider the search or genre endpoints for more diversity.
+ */
 public class DeezerMusicService implements MusicService {
 
+    /** Deezer global chart endpoint — returns the current top 50 tracks. */
     private static final String CHART_URL = "https://api.deezer.com/chart/0/tracks?limit=50";
 
+    /**
+     * Fetches tracks on a background thread and posts results back to the GL thread.
+     *
+     * @param count    max number of tracks to return
+     * @param callback delivers the track list on success, or an error message on failure
+     */
     @Override
     public void fetchTracks(int count, MusicServiceCallback callback) {
         new Thread(() -> {
diff --git a/android/src/main/java/group07/beatbattle/android/firebase/AndroidFirebaseGateway.java b/android/src/main/java/group07/beatbattle/android/firebase/AndroidFirebaseGateway.java
index c6fe312..931a2a8 100644
--- a/android/src/main/java/group07/beatbattle/android/firebase/AndroidFirebaseGateway.java
+++ b/android/src/main/java/group07/beatbattle/android/firebase/AndroidFirebaseGateway.java
@@ -4,6 +4,12 @@
 
 import group07.beatbattle.firebase.FirebaseGateway;
 
+/**
+ * Android implementation of FirebaseGateway.
+ * Thin delegation layer, every method forwards to FirestoreSessionRepository.
+ * Separating this from the repository makes it easy to add more data sources later
+ * (e.g. analytics, auth) without touching core code.
+ */
 public class AndroidFirebaseGateway implements FirebaseGateway {
 
     private final FirestoreSessionRepository sessionRepository;
diff --git a/android/src/main/java/group07/beatbattle/android/firebase/FirestoreSessionRepository.java b/android/src/main/java/group07/beatbattle/android/firebase/FirestoreSessionRepository.java
index 3722644..de90219 100644
--- a/android/src/main/java/group07/beatbattle/android/firebase/FirestoreSessionRepository.java
+++ b/android/src/main/java/group07/beatbattle/android/firebase/FirestoreSessionRepository.java
@@ -16,6 +16,18 @@
 import group07.beatbattle.firebase.FirebaseGateway;
 import group07.beatbattle.model.Player;
 
+/**
+ * Direct Firestore data-access layer for all session-related operations.
+ *
+ * Collections:
+ *   Sessions          — top-level game state, pin, round index
+ *   Sessions/Players  — per-player name, score, host flag
+ *   Sessions/Questions — round questions stored by the host at game start
+ *   Sessions/Answers  — one doc per player per round, used to detect when everyone has answered
+ *
+ * Real-time listeners (listenToPlayers, listenToSessionState, listenToRoundAnswerCount)
+ * stay active until the app process ends or the registration is explicitly removed.
+ */
 public class FirestoreSessionRepository {
 
     private static final String SESSIONS = "Sessions";
diff --git a/core/src/main/java/group07/beatbattle/BeatBattle.java b/core/src/main/java/group07/beatbattle/BeatBattle.java
index 9f2eb24..65e21e4 100644
--- a/core/src/main/java/group07/beatbattle/BeatBattle.java
+++ b/core/src/main/java/group07/beatbattle/BeatBattle.java
@@ -20,6 +20,13 @@
 import group07.beatbattle.ui.components.JoinCreateButton;
 import group07.beatbattle.ui.style.InputFieldStyles;
 
+/**
+ * Root libGDX Game class and central dependency holder for BeatBattle.
+ * Loads and owns the shared fonts (Montserrat, Orbitron, Oswald).
+ * Holds platform-injected services: FirebaseGateway, MusicService, AudioPlayer.
+ * Stores the local player's identity, session membership, and the active GameSession.
+ * Platform dependencies are injected by AndroidLauncher before create() is called.
+ */
 public class BeatBattle extends Game {
 
     private final FirebaseGateway firebaseGateway;
diff --git a/core/src/main/java/group07/beatbattle/audio/AudioPlayer.java b/core/src/main/java/group07/beatbattle/audio/AudioPlayer.java
index e62905c..5599e99 100644
--- a/core/src/main/java/group07/beatbattle/audio/AudioPlayer.java
+++ b/core/src/main/java/group07/beatbattle/audio/AudioPlayer.java
@@ -1,8 +1,23 @@
 package group07.beatbattle.audio;
 
+/**
+ * Interface for streaming audio previews during a game round.
+ * Implemented by AndroidAudioPlayer on Android, and NoOpAudioPlayer on desktop.
+ */
 public interface AudioPlayer {
+    /** Starts streaming audio from the given URL. Stops any current track first. */
     void play(String url);
+
+    /** Stops and releases the current track. */
     void stop();
+
+    /**
+     * Mutes or unmutes playback without stopping the stream.
+     *
+     * @param muted true to mute, false to unmute
+     */
     void setMuted(boolean muted);
+
+    /** Releases all resources. Call when the app is shutting down. */
     void dispose();
 }
diff --git a/core/src/main/java/group07/beatbattle/controller/LeaderboardController.java b/core/src/main/java/group07/beatbattle/controller/LeaderboardController.java
index 74a3607..30804db 100644
--- a/core/src/main/java/group07/beatbattle/controller/LeaderboardController.java
+++ b/core/src/main/java/group07/beatbattle/controller/LeaderboardController.java
@@ -12,6 +12,16 @@
 import group07.beatbattle.states.StartState;
 import group07.beatbattle.states.StateManager;
 
+/**
+ * Controls the leaderboard screen shown between rounds and at game over.
+ *
+ * Host behaviour: onNextRound() writes the new round index to Firestore before
+ * launching the next RoundController, so joiners are kept in sync.
+ * onGameOver() writes "game_over" to Firestore then transitions to GameOverState.
+ *
+ * Joiner behaviour: joiners do not call onNextRound() or onGameOver() directly —
+ * they follow the host via the session-state listener started in LobbyController.
+ */
 public class LeaderboardController {
 
     private final BeatBattle game;
diff --git a/core/src/main/java/group07/beatbattle/controller/LobbyController.java b/core/src/main/java/group07/beatbattle/controller/LobbyController.java
index 6986237..5852b27 100644
--- a/core/src/main/java/group07/beatbattle/controller/LobbyController.java
+++ b/core/src/main/java/group07/beatbattle/controller/LobbyController.java
@@ -28,6 +28,16 @@
 import group07.beatbattle.view.JoinCreateView;
 import group07.beatbattle.view.LobbyView;
 
+/**
+ * Orchestrates pre-game and inter-round navigation for both the host and joiners.
+ *
+ * Host path: onStartGame() fetches tracks from Deezer, builds questions, stores them
+ * in Firestore, sets state to "in_round", then launches the first RoundController.
+ *
+ * Joiner path: onGameStarted() reads questions from Firestore and starts a persistent
+ * session-state listener that routes the joiner through leaderboard -> next round -> game over,
+ * driven entirely by what the host writes to Firestore.
+ */
 public class LobbyController {
 
     private static final int OPTIONS_PER_Q = 4;
@@ -259,8 +269,8 @@ public void onGameStarted(
     }
 
     /**
-     * Joiners: single Firestore listener that routes through leaderboard →
-     * next round → game over, driven by what the host writes.
+     * Joiners: single Firestore listener that routes through leaderboard ->
+     * next round -> game over, driven by what the host writes.
      */
     private void startJoinerSyncListener(String sessionId, GameSession session) {
         // Track the last state+round we handled to avoid duplicate transitions.
@@ -384,7 +394,7 @@ private void buildAndStartSession(String sessionId, List<Player> sessionPlayers,
 
         game.setCurrentSession(session);
 
-        // Store questions → update state → launch round
+        // Store questions -> update state -> launch round
         game.getFirebaseGateway().storeQuestions(
             sessionId,
             questionDataList,
diff --git a/core/src/main/java/group07/beatbattle/controller/RoundController.java b/core/src/main/java/group07/beatbattle/controller/RoundController.java
index 2614fc3..2d3714b 100644
--- a/core/src/main/java/group07/beatbattle/controller/RoundController.java
+++ b/core/src/main/java/group07/beatbattle/controller/RoundController.java
@@ -20,6 +20,16 @@
 import group07.beatbattle.states.StartState;
 import group07.beatbattle.states.StateManager;
 
+/**
+ * Controls the lifecycle of a single game round.
+ * On construction creates an ECS round entity, starts audio playback, and (if host)
+ * starts a Firestore listener that advances the game as soon as all players have answered.
+ *
+ * Flow:
+ *   1. Player answers -> onAnswerSubmitted() scores it and records it in Firebase.
+ *   2. Timer expires (host only) -> onRoundExpired() triggers the leaderboard transition.
+ *   3. Leaderboard transition fetches fresh scores from Firebase then hands off to LeaderboardController.
+ */
 public class RoundController {
 
     private final BeatBattle game;
diff --git a/core/src/main/java/group07/beatbattle/ecs/entities/RoundFactory.java b/core/src/main/java/group07/beatbattle/ecs/entities/RoundFactory.java
index fd7a7e0..9a0a30e 100644
--- a/core/src/main/java/group07/beatbattle/ecs/entities/RoundFactory.java
+++ b/core/src/main/java/group07/beatbattle/ecs/entities/RoundFactory.java
@@ -4,6 +4,10 @@
 import group07.beatbattle.ecs.components.TimerComponent;
 import group07.beatbattle.model.GameRules;
 
+/**
+ * Creates ECS round entities used by AudioSystem and RoundSystem.
+ * Each entity gets an AudioComponent (song preview URL) and a TimerComponent (round duration).
+ */
 public class RoundFactory {
     private static RoundFactory instance;
 
diff --git a/core/src/main/java/group07/beatbattle/ecs/systems/AudioSystem.java b/core/src/main/java/group07/beatbattle/ecs/systems/AudioSystem.java
index bd837b0..e38ab6a 100644
--- a/core/src/main/java/group07/beatbattle/ecs/systems/AudioSystem.java
+++ b/core/src/main/java/group07/beatbattle/ecs/systems/AudioSystem.java
@@ -6,6 +6,12 @@
 
 import java.util.List;
 
+/**
+ * ECS system that controls music preview playback during game rounds.
+ * Playback is event-driven via play/stop calls rather than running on every tick.
+ * Mute state is stored here so it persists across round transitions,
+ * GameRoundView reads it via isMuted() on construction.
+ */
 public class AudioSystem extends EntitySystem {
     private static AudioSystem instance;
     private AudioPlayer audioPlayer;
diff --git a/core/src/main/java/group07/beatbattle/firebase/FirebaseGateway.java b/core/src/main/java/group07/beatbattle/firebase/FirebaseGateway.java
index d539696..d9ce62f 100644
--- a/core/src/main/java/group07/beatbattle/firebase/FirebaseGateway.java
+++ b/core/src/main/java/group07/beatbattle/firebase/FirebaseGateway.java
@@ -4,6 +4,18 @@
 
 import group07.beatbattle.model.Player;
 
+/**
+ * Abstraction layer over the Firebase/Firestore backend.
+ * All methods are async and deliver results via callback interfaces defined as inner types.
+ * Keeps Firebase SDK code out of the core module.
+ * NoOpFirebaseGateway is used for the desktop/LWJGL3 build where Firebase is unavailable.
+ *
+ * Firestore data model:
+ *   Sessions/{sessionId}
+ *     Players/{playerId}       — name, score, isHost
+ *     Questions/{roundIndex}   — songId, songTitle, songArtist, previewUrl, options[]
+ *     Answers/{round}_{player} — roundIndex, playerId
+ */
 public interface FirebaseGateway {
 
     void gamePinExists(String gamePin, GamePinExistsCallback callback);
diff --git a/core/src/main/java/group07/beatbattle/model/AnswerSubmission.java b/core/src/main/java/group07/beatbattle/model/AnswerSubmission.java
index 2fddbdd..2b2220a 100644
--- a/core/src/main/java/group07/beatbattle/model/AnswerSubmission.java
+++ b/core/src/main/java/group07/beatbattle/model/AnswerSubmission.java
@@ -1,5 +1,9 @@
 package group07.beatbattle.model;
 
+/**
+ * Immutable record of a player's answer for a single round.
+ * Stores what they answered, when they answered, whether it was correct, and how many points were awarded.
+ */
 public class AnswerSubmission {
 
     private final String playerId;
diff --git a/core/src/main/java/group07/beatbattle/model/GameMode.java b/core/src/main/java/group07/beatbattle/model/GameMode.java
index f8a5251..fe3a04b 100644
--- a/core/src/main/java/group07/beatbattle/model/GameMode.java
+++ b/core/src/main/java/group07/beatbattle/model/GameMode.java
@@ -1,5 +1,6 @@
 package group07.beatbattle.model;
 
+/** Whether the local player is creating a new session or joining an existing one. */
 public enum GameMode {
     JOIN,
     CREATE
diff --git a/core/src/main/java/group07/beatbattle/model/GameRules.java b/core/src/main/java/group07/beatbattle/model/GameRules.java
index 9876e66..af178ee 100644
--- a/core/src/main/java/group07/beatbattle/model/GameRules.java
+++ b/core/src/main/java/group07/beatbattle/model/GameRules.java
@@ -1,5 +1,6 @@
 package group07.beatbattle.model;
 
+/** Central place for game constants shared across systems (e.g. round duration). */
 public final class GameRules {
 
     public static final float ROUND_DURATION_SECONDS = 30f;
diff --git a/core/src/main/java/group07/beatbattle/model/GameSession.java b/core/src/main/java/group07/beatbattle/model/GameSession.java
index cb65132..3d35741 100644
--- a/core/src/main/java/group07/beatbattle/model/GameSession.java
+++ b/core/src/main/java/group07/beatbattle/model/GameSession.java
@@ -4,6 +4,11 @@
 import java.util.Collections;
 import java.util.List;
 
+/**
+ * Holds all state for an active game session: players, questions, and round progress.
+ * Created by the host when the game starts and shared (via Firestore) with all joiners.
+ * currentRoundIndex tracks which question is active and advances via advanceRound().
+ */
 public class GameSession {
 
     public enum State {
diff --git a/core/src/main/java/group07/beatbattle/model/Leaderboard.java b/core/src/main/java/group07/beatbattle/model/Leaderboard.java
index f9836f1..70b968a 100644
--- a/core/src/main/java/group07/beatbattle/model/Leaderboard.java
+++ b/core/src/main/java/group07/beatbattle/model/Leaderboard.java
@@ -5,6 +5,10 @@
 import java.util.Comparator;
 import java.util.List;
 
+/**
+ * Sorted list of LeaderboardEntry objects built from the current player scores.
+ * Players are ranked highest score first on construction.
+ */
 public class Leaderboard {
 
     private final List<LeaderboardEntry> entries;
diff --git a/core/src/main/java/group07/beatbattle/model/LeaderboardEntry.java b/core/src/main/java/group07/beatbattle/model/LeaderboardEntry.java
index 4d203a9..31d444d 100644
--- a/core/src/main/java/group07/beatbattle/model/LeaderboardEntry.java
+++ b/core/src/main/java/group07/beatbattle/model/LeaderboardEntry.java
@@ -1,5 +1,9 @@
 package group07.beatbattle.model;
 
+/**
+ * A single row on the leaderboard.
+ * Holds the player's total score, their score for the last round, and their rank position.
+ */
 public class LeaderboardEntry {
 
     private final String playerId;
diff --git a/core/src/main/java/group07/beatbattle/model/Player.java b/core/src/main/java/group07/beatbattle/model/Player.java
index 3df88f7..3fd4753 100644
--- a/core/src/main/java/group07/beatbattle/model/Player.java
+++ b/core/src/main/java/group07/beatbattle/model/Player.java
@@ -1,5 +1,9 @@
 package group07.beatbattle.model;
 
+/**
+ * Represents a player in a game session.
+ * Tracks cumulative score across all rounds and the score earned in the most recent round.
+ */
 public class Player {
 
     private final String id;
diff --git a/core/src/main/java/group07/beatbattle/model/Question.java b/core/src/main/java/group07/beatbattle/model/Question.java
index db0440a..d864841 100644
--- a/core/src/main/java/group07/beatbattle/model/Question.java
+++ b/core/src/main/java/group07/beatbattle/model/Question.java
@@ -2,6 +2,11 @@
 
 import java.util.List;
 
+/**
+ * A single quiz question for one round.
+ * Contains the correct song, a list of answer options (shuffled, including the correct title),
+ * and the round index it belongs to. The correct answer is always the song's title.
+ */
 public class Question {
 
     private final String id;
diff --git a/core/src/main/java/group07/beatbattle/model/SessionCreationResult.java b/core/src/main/java/group07/beatbattle/model/SessionCreationResult.java
index 2b568c3..ffbf73c 100644
--- a/core/src/main/java/group07/beatbattle/model/SessionCreationResult.java
+++ b/core/src/main/java/group07/beatbattle/model/SessionCreationResult.java
@@ -1,5 +1,6 @@
 package group07.beatbattle.model;
 
+/** Result returned by LobbyService after successfully creating a session. */
 public class SessionCreationResult {
     private final String sessionId;
     private final String gamePin;
diff --git a/core/src/main/java/group07/beatbattle/model/SessionJoinResult.java b/core/src/main/java/group07/beatbattle/model/SessionJoinResult.java
index 9ea6bd4..75d9449 100644
--- a/core/src/main/java/group07/beatbattle/model/SessionJoinResult.java
+++ b/core/src/main/java/group07/beatbattle/model/SessionJoinResult.java
@@ -1,5 +1,6 @@
 package group07.beatbattle.model;
 
+/** Result returned by LobbyService after successfully joining a session. */
 public class SessionJoinResult {
     private final String sessionId;
     private final String gamePin;
diff --git a/core/src/main/java/group07/beatbattle/model/Song.java b/core/src/main/java/group07/beatbattle/model/Song.java
index d1093e8..9262a79 100644
--- a/core/src/main/java/group07/beatbattle/model/Song.java
+++ b/core/src/main/java/group07/beatbattle/model/Song.java
@@ -1,5 +1,9 @@
 package group07.beatbattle.model;
 
+/**
+ * Represents a song fetched from the Deezer API.
+ * Holds metadata (title, artist, album art) and the 30-second preview URL used for playback.
+ */
 public class Song {
 
     private final String id;
diff --git a/core/src/main/java/group07/beatbattle/model/score/ScoreCalculator.java b/core/src/main/java/group07/beatbattle/model/score/ScoreCalculator.java
index 29dc0f7..2b96a8f 100644
--- a/core/src/main/java/group07/beatbattle/model/score/ScoreCalculator.java
+++ b/core/src/main/java/group07/beatbattle/model/score/ScoreCalculator.java
@@ -2,13 +2,22 @@
 
 import group07.beatbattle.model.GameRules;
 
+/**
+ * Calculates the score awarded for a round based on answer correctness and speed.
+ *
+ * Scoring rules:
+ *   - Wrong answer: 0 points.
+ *   - Correct answer within the grace period (first 3 seconds): 1000 points.
+ *   - Correct answer after the grace period: linear decay from 1000 down to 300,
+ *     reaching 300 at the end of the round timer.
+ */
 public class ScoreCalculator {
 
     private static final int MAX_POINTS = 1000;
     private static final int MIN_POINTS = 300;
     private static final double ROUND_TIME_SECONDS = GameRules.ROUND_DURATION_SECONDS;
 
-    private static final double GRACE_PERIOD_SECONDS = 5.0;
+    private static final double GRACE_PERIOD_SECONDS = 3.0;
 
     public static int calculateScore(boolean isCorrect, double answerTimeSeconds) {
         if (!isCorrect) {
@@ -38,7 +47,7 @@ public static int calculateScore(boolean isCorrect, double answerTimeSeconds) {
 
     public static void main(String[] args) {
         System.out.println(calculateScore(true, 0.0));    // 1000
-        System.out.println(calculateScore(true, 5.0));    // breaking point for high score
+        System.out.println(calculateScore(true, 3.0));    // breaking point for high score
         System.out.println(calculateScore(true, 15.0));   // midpoint (500)
         System.out.println(calculateScore(true, 29.9));   // 300
         System.out.println(calculateScore(false, 10.0));  // 0
diff --git a/core/src/main/java/group07/beatbattle/model/services/LobbyService.java b/core/src/main/java/group07/beatbattle/model/services/LobbyService.java
index c1cbbf2..b15072f 100644
--- a/core/src/main/java/group07/beatbattle/model/services/LobbyService.java
+++ b/core/src/main/java/group07/beatbattle/model/services/LobbyService.java
@@ -8,6 +8,12 @@
 import group07.beatbattle.model.SessionJoinResult;
 import group07.beatbattle.model.Player;
 
+/**
+ * Handles creating, joining, and leaving lobby sessions.
+ * Validates name, game pin, and round count before touching Firebase.
+ * Game pins are 4-character alphanumeric (A-Z0-9), checked for uniqueness against Firestore.
+ * Player/host IDs are time-based ("host-<millis>") — fine for now but consider UUID for production.
+ */
 public class LobbyService {
 
     public interface CreateSessionCallback {
diff --git a/core/src/main/java/group07/beatbattle/service/MusicService.java b/core/src/main/java/group07/beatbattle/service/MusicService.java
index 86dfbcf..801bf72 100644
--- a/core/src/main/java/group07/beatbattle/service/MusicService.java
+++ b/core/src/main/java/group07/beatbattle/service/MusicService.java
@@ -1,5 +1,15 @@
 package group07.beatbattle.service;
 
+/**
+ * Interface for fetching song tracks used to build quiz questions.
+ * Implemented by DeezerMusicService on Android.
+ */
 public interface MusicService {
+    /**
+     * Fetches a list of tracks asynchronously.
+     *
+     * @param count    number of tracks requested
+     * @param callback delivers the track list on success, or an error message on failure
+     */
     void fetchTracks(int count, MusicServiceCallback callback);
 }
diff --git a/core/src/main/java/group07/beatbattle/states/GameOverState.java b/core/src/main/java/group07/beatbattle/states/GameOverState.java
index bd4b752..09d9307 100644
--- a/core/src/main/java/group07/beatbattle/states/GameOverState.java
+++ b/core/src/main/java/group07/beatbattle/states/GameOverState.java
@@ -4,6 +4,7 @@
 import group07.beatbattle.controller.LeaderboardController;
 import group07.beatbattle.view.GameOverView;
 
+/** State for the final game over screen shown after all rounds are completed. */
 public class GameOverState extends State {
 
     private final LeaderboardController leaderboardController;
diff --git a/core/src/main/java/group07/beatbattle/states/InRoundState.java b/core/src/main/java/group07/beatbattle/states/InRoundState.java
index 38c9528..d02cd88 100644
--- a/core/src/main/java/group07/beatbattle/states/InRoundState.java
+++ b/core/src/main/java/group07/beatbattle/states/InRoundState.java
@@ -4,6 +4,7 @@
 import group07.beatbattle.controller.RoundController;
 import group07.beatbattle.view.GameRoundView;
 
+/** State for an active quiz round. Sets the screen to GameRoundView. */
 public class InRoundState extends State {
 
     private final RoundController roundController;
diff --git a/core/src/main/java/group07/beatbattle/states/JoinCreateState.java b/core/src/main/java/group07/beatbattle/states/JoinCreateState.java
index 0668def..3caefd4 100644
--- a/core/src/main/java/group07/beatbattle/states/JoinCreateState.java
+++ b/core/src/main/java/group07/beatbattle/states/JoinCreateState.java
@@ -5,6 +5,7 @@
 import group07.beatbattle.model.GameMode;
 import group07.beatbattle.view.JoinCreateView;
 
+/** State for the name/pin entry screen. Mode determines whether the player is creating or joining. */
 public class JoinCreateState extends State {
 
     private final GameMode mode;
diff --git a/core/src/main/java/group07/beatbattle/states/LeaderboardState.java b/core/src/main/java/group07/beatbattle/states/LeaderboardState.java
index 6421dcf..f7863ed 100644
--- a/core/src/main/java/group07/beatbattle/states/LeaderboardState.java
+++ b/core/src/main/java/group07/beatbattle/states/LeaderboardState.java
@@ -4,6 +4,7 @@
 import group07.beatbattle.controller.LeaderboardController;
 import group07.beatbattle.view.LeaderboardView;
 
+/** State for the between-round leaderboard screen. */
 public class LeaderboardState extends State {
 
     private final LeaderboardController leaderboardController;
diff --git a/core/src/main/java/group07/beatbattle/states/LobbyState.java b/core/src/main/java/group07/beatbattle/states/LobbyState.java
index 7ed79a8..88d74d5 100644
--- a/core/src/main/java/group07/beatbattle/states/LobbyState.java
+++ b/core/src/main/java/group07/beatbattle/states/LobbyState.java
@@ -5,6 +5,7 @@
 import group07.beatbattle.model.GameMode;
 import group07.beatbattle.view.LobbyView;
 
+/** State for the waiting room where players gather before the host starts the game. */
 public class LobbyState extends State {
 
     private final LobbyView view;
diff --git a/core/src/main/java/group07/beatbattle/states/SettingsState.java b/core/src/main/java/group07/beatbattle/states/SettingsState.java
index b250882..4dbba40 100644
--- a/core/src/main/java/group07/beatbattle/states/SettingsState.java
+++ b/core/src/main/java/group07/beatbattle/states/SettingsState.java
@@ -5,6 +5,7 @@
 import group07.beatbattle.view.SettingsView;
 
 
+/** State for the settings screen, accessible from the lobby. */
 public class SettingsState extends State {
 
     private final SettingsView view;
diff --git a/core/src/main/java/group07/beatbattle/states/StartState.java b/core/src/main/java/group07/beatbattle/states/StartState.java
index 5e007b5..3193922 100644
--- a/core/src/main/java/group07/beatbattle/states/StartState.java
+++ b/core/src/main/java/group07/beatbattle/states/StartState.java
@@ -4,6 +4,7 @@
 import group07.beatbattle.controller.LobbyController;
 import group07.beatbattle.view.StartView;
 
+/** State for the main menu screen. Entry point of the app after launch. */
 public class StartState extends State {
 
     private final LobbyController lobbyController;
diff --git a/core/src/main/java/group07/beatbattle/states/State.java b/core/src/main/java/group07/beatbattle/states/State.java
index 41522db..2d5140b 100644
--- a/core/src/main/java/group07/beatbattle/states/State.java
+++ b/core/src/main/java/group07/beatbattle/states/State.java
@@ -2,6 +2,10 @@
 
 import group07.beatbattle.BeatBattle;
 
+/**
+ * Base class for all application states.
+ * StateManager calls enter() when switching to this state and exit() when leaving it.
+ */
 public abstract class State {
 
     protected final BeatBattle game;
diff --git a/core/src/main/java/group07/beatbattle/states/StateManager.java b/core/src/main/java/group07/beatbattle/states/StateManager.java
index 994c7cb..15ad162 100644
--- a/core/src/main/java/group07/beatbattle/states/StateManager.java
+++ b/core/src/main/java/group07/beatbattle/states/StateManager.java
@@ -1,5 +1,10 @@
 package group07.beatbattle.states;
 
+/**
+ * Singleton that manages the active screen state.
+ * setState() exits the current state then enters the new one.
+ * States: StartState, JoinCreateState, LobbyState, InRoundState, LeaderboardState, GameOverState, SettingsState.
+ */
 public class StateManager {
 
     private static StateManager instance;
diff --git a/core/src/main/java/group07/beatbattle/utils/.gitkeep b/core/src/main/java/group07/beatbattle/utils/.gitkeep
deleted file mode 100644
index e69de29..0000000