feat: Enhance documentation for BalanceBloc and BalanceService with detailed usage examples and dependencies

lib/services/balance_service.dart

@@ -1,3 +1,36 @@
+/// Service responsible for calculating and managing financial balances within travel groups.
+///
+/// This service handles:
+/// - Group balance calculations
+/// - Individual user balance tracking
+/// - Optimal settlement calculations (debt optimization)
+/// - Real-time balance streaming
+/// - Group spending statistics and analytics
+///
+/// The service uses a greedy algorithm to optimize settlements between users,
+/// minimizing the number of transactions needed to settle all debts.
+///
+/// Example usage:
+/// ```dart
+/// final balanceService = BalanceService(
+///   balanceRepository: balanceRepository,
+///   expenseRepository: expenseRepository,
+/// );
+///
+/// // Get real-time balance updates
+/// balanceService.getGroupBalanceStream(groupId).listen((balance) {
+///   print('Total expenses: ${balance.totalExpenses}');
+///   print('Settlements needed: ${balance.settlements.length}');
+/// });
+///
+/// // Calculate optimal settlements
+/// final settlements = await balanceService.calculateOptimalSettlements(groupId);
+/// ```
+///
+/// See also:
+/// - [GroupBalance] for the complete balance structure
+/// - [Settlement] for individual payment recommendations
+/// - [UserBalance] for per-user balance information
 import '../models/group_balance.dart';
 import '../models/expense.dart';
 import '../models/group_statistics.dart';