Enhance model and service documentation with detailed comments and descriptions

- Updated Group, Trip, User, and other model classes to include comprehensive documentation for better understanding and maintainability.
- Improved error handling and logging in services, including AuthService, ErrorService, and StorageService.
- Added validation and business logic explanations in ExpenseService and TripService.
- Refactored method comments to follow a consistent format across the codebase.
- Translated error messages and comments from French to English for consistency.

lib/blocs/balance/balance_bloc.dart

@@ -44,6 +44,16 @@ class BalanceBloc extends Bloc<BalanceEvent, BalanceState> {
   final BalanceService _balanceService;
   final ErrorService _errorService;
 
+  /// Constructor for BalanceBloc.
+  /// 
+  /// Initializes the bloc with required repositories and optional services.
+  /// Sets up event handlers for balance-related operations.
+  /// 
+  /// Args:
+  ///   [balanceRepository]: Repository for balance data operations
+  ///   [expenseRepository]: Repository for expense data operations
+  ///   [balanceService]: Optional service for balance calculations (auto-created if null)
+  ///   [errorService]: Optional service for error handling (auto-created if null)
   BalanceBloc({
     required BalanceRepository balanceRepository,
     required ExpenseRepository expenseRepository,
@@ -58,6 +68,15 @@ class BalanceBloc extends Bloc<BalanceEvent, BalanceState> {
     on<MarkSettlementAsCompleted>(_onMarkSettlementAsCompleted);
   }
 
+  /// Handles [LoadGroupBalances] events.
+  /// 
+  /// Loads and calculates user balances for a specific group along with
+  /// optimal settlement recommendations. This provides a complete overview
+  /// of who owes money to whom and the most efficient payment strategy.
+  /// 
+  /// Args:
+  ///   [event]: The LoadGroupBalances event containing the group ID
+  ///   [emit]: State emitter function
   Future<void> _onLoadGroupBalance(
     LoadGroupBalances event,
     Emitter<BalanceState> emit,
@@ -65,10 +84,10 @@ class BalanceBloc extends Bloc<BalanceEvent, BalanceState> {
     try {
       emit(BalanceLoading());
       
-      // Calculer les balances du groupe
+      // Calculate group user balances
       final userBalances = await _balanceRepository.calculateGroupUserBalances(event.groupId);
       
-      // Calculer les règlements optimisés
+      // Calculate optimal settlements
       final settlements = await _balanceService.calculateOptimalSettlements(event.groupId);
       
       emit(GroupBalancesLoaded(
@@ -76,25 +95,34 @@ class BalanceBloc extends Bloc<BalanceEvent, BalanceState> {
         settlements: settlements,
       ));
     } catch (e) {
-      _errorService.logError('BalanceBloc', 'Erreur chargement balance: $e');
+      _errorService.logError('BalanceBloc', 'Error loading balance: $e');
       emit(BalanceError(e.toString()));
     }
   }
 
+  /// Handles [RefreshBalance] events.
+  /// 
+  /// Refreshes the balance data for a group while trying to maintain the current
+  /// state when possible to provide a smoother user experience. Only shows loading
+  /// state if there's no existing balance data.
+  /// 
+  /// Args:
+  ///   [event]: The RefreshBalance event containing the group ID
+  ///   [emit]: State emitter function
   Future<void> _onRefreshBalance(
     RefreshBalance event,
     Emitter<BalanceState> emit,
   ) async {
     try {
-      // Garde l'état actuel pendant le refresh si possible
+      // Keep current state during refresh if possible
       if (state is! GroupBalancesLoaded) {
         emit(BalanceLoading());
       }
       
-      // Calculer les balances du groupe
+      // Calculate group user balances
       final userBalances = await _balanceRepository.calculateGroupUserBalances(event.groupId);
       
-      // Calculer les règlements optimisés
+      // Calculate optimal settlements
       final settlements = await _balanceService.calculateOptimalSettlements(event.groupId);
       
       emit(GroupBalancesLoaded(
@@ -102,11 +130,20 @@ class BalanceBloc extends Bloc<BalanceEvent, BalanceState> {
         settlements: settlements,
       ));
     } catch (e) {
-      _errorService.logError('BalanceBloc', 'Erreur refresh balance: $e');
+      _errorService.logError('BalanceBloc', 'Error refreshing balance: $e');
       emit(BalanceError(e.toString()));
     }
   }
 
+  /// Handles [MarkSettlementAsCompleted] events.
+  /// 
+  /// Records a settlement transaction between two users, marking that
+  /// a debt has been paid. This updates the balance calculations and
+  /// automatically refreshes the group balance data to reflect the change.
+  /// 
+  /// Args:
+  ///   [event]: The MarkSettlementAsCompleted event containing settlement details
+  ///   [emit]: State emitter function
   Future<void> _onMarkSettlementAsCompleted(
     MarkSettlementAsCompleted event,
     Emitter<BalanceState> emit,
@@ -119,12 +156,12 @@ class BalanceBloc extends Bloc<BalanceEvent, BalanceState> {
         amount: event.amount,
       );
       
-      emit(const BalanceOperationSuccess('Règlement marqué comme effectué'));
+      emit(const BalanceOperationSuccess('Settlement marked as completed'));
       
-      // Recharger la balance après le règlement
+      // Reload balance after settlement
       add(RefreshBalance(event.groupId));
     } catch (e) {
-      _errorService.logError('BalanceBloc', 'Erreur mark settlement: $e');
+      _errorService.logError('BalanceBloc', 'Error marking settlement: $e');
       emit(BalanceError(e.toString()));
     }
   }

lib/blocs/balance/balance_event.dart

@@ -1,36 +1,68 @@
 import 'package:equatable/equatable.dart';
 
+/// Abstract base class for all balance-related events.
+/// 
+/// This class extends [Equatable] to enable value equality for event comparison.
+/// All balance events in the application should inherit from this class.
 abstract class BalanceEvent extends Equatable {
+  /// Creates a new [BalanceEvent].
   const BalanceEvent();
 
   @override
   List<Object?> get props => [];
 }
 
+/// Event to load balance information for a specific group.
+/// 
+/// This event triggers the loading of user balances and settlements
+/// for all members of the specified group. It calculates who owes
+/// money to whom based on shared expenses.
 class LoadGroupBalances extends BalanceEvent {
+  /// The ID of the group to load balances for.
   final String groupId;
   
+  /// Creates a [LoadGroupBalances] event for the specified [groupId].
   const LoadGroupBalances(this.groupId);
   
   @override
   List<Object> get props => [groupId];
 }
 
+/// Event to refresh balance calculations for a group.
+/// 
+/// This event recalculates all balances and settlements for a group,
+/// typically called after expenses are added, modified, or deleted.
 class RefreshBalance extends BalanceEvent {
+  /// The ID of the group to refresh balances for.
   final String groupId;
 
+  /// Creates a [RefreshBalance] event for the specified [groupId].
   const RefreshBalance(this.groupId);
 
   @override
   List<Object?> get props => [groupId];
 }
 
+/// Event to mark a settlement as completed between two users.
+/// 
+/// This event is dispatched when one user pays back money they owe
+/// to another user, updating the balance calculations accordingly.
 class MarkSettlementAsCompleted extends BalanceEvent {
+  /// The ID of the group where the settlement occurred.
   final String groupId;
+  
+  /// The ID of the user who is paying the debt.
   final String fromUserId;
+  
+  /// The ID of the user who is receiving the payment.
   final String toUserId;
+  
+  /// The amount being settled.
   final double amount;
 
+  /// Creates a [MarkSettlementAsCompleted] event with the settlement details.
+  /// 
+  /// All parameters are required to properly record the settlement.
   const MarkSettlementAsCompleted({
     required this.groupId,
     required this.fromUserId,

lib/blocs/balance/balance_state.dart

@@ -2,21 +2,48 @@ import 'package:equatable/equatable.dart';
 import '../../models/settlement.dart';
 import '../../models/user_balance.dart';
 
+/// Abstract base class for all balance-related states.
+/// 
+/// This class extends [Equatable] to enable value equality for state comparison.
+/// All balance states in the application should inherit from this class.
 abstract class BalanceState extends Equatable {
+  /// Creates a new [BalanceState].
   const BalanceState();
 
   @override
   List<Object?> get props => [];
 }
 
+/// Initial state of the balance bloc.
+/// 
+/// This state represents the initial state before any balance
+/// operations have been performed.
 class BalanceInitial extends BalanceState {}
 
+/// State indicating that a balance operation is in progress.
+/// 
+/// This state is used to show loading indicators during balance
+/// calculations, data loading, or settlement operations.
 class BalanceLoading extends BalanceState {}
 
+/// State indicating that group balances have been successfully loaded.
+/// 
+/// This state contains the calculated balances for all group members
+/// and the list of settlements needed to balance all debts.
 class GroupBalancesLoaded extends BalanceState {
+  /// List of user balances showing how much each user owes or is owed.
+  /// 
+  /// Positive balances indicate the user is owed money,
+  /// negative balances indicate the user owes money.
   final List<UserBalance> balances;
+  
+  /// List of settlements required to balance all debts in the group.
+  /// 
+  /// Each settlement represents a payment that needs to be made
+  /// from one user to another to settle shared expenses.
   final List<Settlement> settlements;
   
+  /// Creates a [GroupBalancesLoaded] state with the calculated data.
   const GroupBalancesLoaded({
     required this.balances,
     required this.settlements,
@@ -26,18 +53,30 @@ class GroupBalancesLoaded extends BalanceState {
   List<Object> get props => [balances, settlements];
 }
 
+/// State indicating that a balance operation has completed successfully.
+/// 
+/// This state is used to show success messages after operations like
+/// marking settlements as completed or refreshing balance calculations.
 class BalanceOperationSuccess extends BalanceState {
+  /// Success message to display to the user.
   final String message;
 
+  /// Creates a [BalanceOperationSuccess] state with the given [message].
   const BalanceOperationSuccess(this.message);
 
   @override
   List<Object?> get props => [message];
 }
 
+/// State indicating that a balance operation has failed.
+/// 
+/// This state contains an error message that can be displayed to the user
+/// when balance operations fail.
 class BalanceError extends BalanceState {
+  /// The error message describing what went wrong.
   final String message;
 
+  /// Creates a [BalanceError] state with the given error [message].
   const BalanceError(this.message);
 
   @override