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()));
     }
   }